home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
EnigmA Amiga Run 1995 October
/
EnigmA AMIGA RUN 01 (1995)(G.R. Edizioni)(IT)[!][issue 1995-10][Aminet 7].iso
/
Aminet
/
dev
/
gui
/
BGUI11c.lha
/
ARexxClass
/
arexxclass.doc
< prev
next >
Wrap
Text File
|
1995-04-23
|
11KB
|
271 lines
File: arexxclass.doc
Description: ARexxClass documentation.
Copyright: (C) Copyright 1994-1995 Jaba Development.
(C) Copyright 1994-1995 Jan van den Baard.
All Rights Reserved.
------------------------------------------------------------------------------
TABLE OF CONTENTS
arexxclass/--background--
arexxclass/Methods
arexxclass/Attributes
arexxclass/--background-- arexxclass/--background--
NAME
Class: arexxclass
Superclass: ROOTCLASS
Include File "ARexxClass.h"
FUNCTION
To provide you with a very easy way to implement an ARexx host in your
programs. The class will take over all the grunt work for you like
host setup, message handling, argument parsing and so on. All you have
to do is to create an object from this class and write the command
code.
NOTE
This class is provided as source code and two linkable ".o" modules.
To make use of this class you should link with the supplied object
code or, if your compiler does not like these object modules, a
re-compiled version of the source.
Also your program must open the following libraries:
intuition.library - V37 or better.
utility.library - V37 or better.
rexxsyslib.library - V36 or better.
dos.library - V37 or better.
Ofcourse these libraries must remain open until you are done using the
class.
There are two linkable object modules supplied both compiled with DICE
v3.0. "arexxclass.o" is an object module which uses normal system
memory allocation/deallocation routines. "arexxclass_p.o" is an object
module which uses memory pools for it's allocations. You will need the
3.1 amiga.lib to link with the later. Both modules are compiled with
registered args turned off.
The source of this class is based on the source output of ARexxBox
V1.12 by Michael Baltzer.
arexxclass/Methods arexxclass/Methods
NEW METHODS
ACM_HANDLE_EVENT -- This method will handle all incoming and outgoing
message traffic from your host. When you are signalled you
simply call this method and everything is done for you.
No return code is specified for this method.
ACM_EXECUTE -- This method allows you to execute one of the commands
from your host. Any unknown command is shipped of to the ARexx
server. This method uses the following custom message
structure:
struct acmExecute {
ULONG MethodID; /* ACM_EXECUTE */
UBYTE *acme_CommandString;
LONG *acme_RC;
LONG *acme_RC2;
UBYTE *acme_Result;
BPTR acme_IO;
};
acme_CommandString -- This must point to the command including
arguments to execute. If the command is found in the
host command list it will be executed. Unknown
commands will be shipped off to the ARexx server.
acme_RC, acme_RC2, acme_Result -- If you wish to know what
errors occured during the execution of the command you
may provide storage pointers here. After the command
executed you will find the errors/result in here.
NOTE: If acme_RC is negative it means that acme_RC2
contains a pointer to an error string instead of
an error number.
acme_IO -- If you execute a script using this method you can
pass a pointer to the IO channel ARexx must use here.
This IO channel will be closed automatically for you
after the command executed.
As errors are reported in acme_RC and acme_RC2 this method
has no specific return code.
CHANGED METHODS
None.
arexxclass/Attributes arexxclass/Attributes
NAME
AC_HostName -- ( STRPTR )
FUNCTION
To supply the object with a base name it must use for it's message
port. Internally this base name is converted to find a unique version.
The class does this by appending a number to the base name. If you
need to know the real host name simply OM_GET it after the object has
been created.
If, for example, you provide a base name of "FOO" the class will
internally try to create a host port with the names "FOO.1", "FOO.2"
... "FOO.99". When none of these names is unique the object creation
fails.
This attribute must be valid or the object will fail to create.
Default is NULL. Applicability is (IG).
NAME
AC_FileExtention -- ( STRPTR )
FUNCTION
To establish the file extention you will be using for your host. This
file extention is used by the ARexx server to determine what file it
should try to open if the original file name did not open.
Default = "rexx". Applicability is (I)
NAME
AC_CommandList -- ( REXXCOMMAND * )
FUNCTION
To provide your host with it's commands. The data must be a valid
pointer to an array of the following structures:
typedef struct {
UBYTE *rc_Name;
UBYTE *rc_ArgTemplate;
VOID (*rc_Func)( REXXARGS *, struct RexxMsg * );
} REXXCOMMAND;
rc_Name -- This must be a pointer to the command name. Although there
are no restrictions it is advisable that commands are in upper
case characters.
rc_ArgTemplate -- If your command expects arguments this must point to
a standard AmigaDOS argument template string. Internally the
class will use ReadArgs() to parse the arguments for the
command. If your command does not expec s arguments you can
set this to NULL.
rc_Func -- This must be a pointer to your command routine. The routine
will get called as follows with the arguments on the stack:
VOID command_func( REXXARGS *ra, struct RexxMsg *rxm );
ra -- This will be a pointer to the following structure:
typedef struct {
ULONG *ra_ArgList;
LONG ra_RC;
LONG ra_RC2;
UBYTE *ra_Result;
} REXXARGS;
ra_ArgList -- This will point to an array of ULONGs containing
the result of the ReadArgs() parse. This may also be
NULL in which case the command does not expect any
arguments.
ra_RC -- In here you can store the primary error (if any).
ra_RC2 -- In here you can store the secundary error. If you
wish to make this a descriptive error string you
should provide a negative primary error code I.E.:
VOID command( REXXARGS *ra, struct RexxMsg *rxm )
{
/* Do your stuff... */
ra->ra_RC = -RC_ERROR;
ra->ra_RC2 = (LONG)"Out of memory!";
}
If you want to provide a descriptive error code you
should provide a positive primary error code I.E.:
VOID command( REXXARGS *ra, struct RexxMsg *rxm )
{
/* Do your stuff... */
ra->ra_RC = RC_ERROR;
ra->ra_RC2 = IoErr();
}
ra_Result -- If your command has a result of some kind you
should store a pointer to that result in here. Please
note that this is expected to be a string so if you
wish to return a numeric result you will have to
convert it to a string first I.E.:
UBYTE buf[ 16 ];
VOID command( REXXARGS *ra, struct RexxMsg *rxm )
{
UWORD number;
/* Do your stuff... */
if ( rxm && rxm->rm_Action & RXFF_RESULT ) {
sprintf( buf, "%ld", number );
ra->ra_Result = buf;
}
}
rxm -- This points to the RexxMessage structure of your command. You
may use this to setup ARexx variables or stem variables.
Please note that this may be NULL.
The array must be terminated with a NULL rc_Name field.
This tag must be valid or the object will fail to create.
Default is NULL. Applicability is (I).
NAME
AC_ErrorCode -- ( ULONG * )
FUNCTION
To provide storage space for the class to store a descriptive error
code if the object creation fails. If the object creation fails the
storage space provided can contain any of the following error codes:
RXERR_NO_COMMAND_LIST -- No command list was provided.
RXERR_NO_PORT_NAME -- No host base name was provided.
RXERR_PORT_ALREADY_EXISTS -- The class was unable to create a unique
name of the base name you provided.
RXERR_OUT_OF_MEMORY -- Not enough free memory.
Default is NULL. Applicability is (I).
SEE ALSO
AC_HostName, AC_CommandList
NAME
AC_RexxHostMask -- ( ULONG * )
FUNCTION
To obtain the host port signal mask.
Example:
Object *AO_Rexx;
ULONG mask, sigrec;
GetAttr( AC_RexxHostMask, AO_Rexx, &mask );
do {
sigrec = Wait( mask );
if ( sigrec & mask )
DoMethod( AO_Rexx, ACM_HANDLE_EVENT );
} while ( ... );
Applicability is (G)